<?xml version="1.0"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html>
	
	<head>
		<meta http-equiv="Content-Language" content="en-gb" />
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <meta name="description" content="Colours, pens and brushes" />
		<title>PDF Graphics .NET documentation - Colours, pens and brushes</title>
		<link rel="stylesheet" href="../style/Help.css" type="text/css" />
	</head>
	
	<body>
		<div class="navigator">
			<span>
				<strong>PDF Graphics .NET</strong> :: <a href="..\Index.html">Help</a> :: <a href="..\Painting_graphics.html">Painting graphics</a> :: Colours, pens and brushes
			</span>
		</div>
		
		<h1>Colours, pens and brushes</h1>

		<p>
			This section covers the following topics:
			<ul>
				<li><a href="#PensBrushes">Pens and brushes</a></li>
				<li><a href="#Colours">Colours</a></li>
				<li><a href="#Lines">Drawing lines</a></li>
				<li><a href="#LineAppearance">Line appearance</a></li>
			</ul>
		</p>
				
		<h2><a name="PensBrushes"></a>Pens and brushes</h2>
		
		<p>In order to paint shapes or draw text onto a page, you will need to use pens and brushes. A <strong>pen</strong> resembles a
			real-world pen and is used to <em>stroke</em>, or in other words; you draw lines with a pen. To fill shapes with a colour,
			you will use a <strong>brush</strong>. 
		</p>
		
		<h3>Pens</h3>
		<p>
			A pen is used to draw lines. Just like a real-world pen, it has a colour and a line thickness. Pens also have some other properties
			that facilitate the drawing of dashed lines, for instance.
			To use a pen, create a new instance of the <span class="code">Pen</span> class. Below is a simple example of pen usage:
		</p>
		
		<div class="sampleCode">Graphics g = new Graphics("Line.pdf");

Pen myPen = new Pen(Rgb.Red);

g.DrawLine(myPen, 0, 20, 500, 20);

g.Close();</div>
				
		<p>
			This draws a red line across the page. The line will have a default thickness of 1 point, which is 1/72<sup>nd</sup> of an inch.
			For more information on the units used in graphics operations, see the <a href="../Advanced_use.html#Units.html">Page units</a> sub-section
			of the <a href="../Advanced_use.html">Advanced Use</a> section.
			To create a pen with a different width, you can use an overloaded constructor and specify the width directly:
		</p>
		
		<div class="sampleCode">Pen myPen = new Pen(Rgb.Red, 0.25f);</div>
		
		<p>This creates a pen that is 1/4<sup>th</sup> of a point wide.</p>
			
		<h3>Brushes</h3>
		
		<p>
			A brush is used to fill shapes and draw text. In its most simple form, a brush has a colour and no other properties;
			it is a solid brush. The section on <a href="Gradients.html">Gradients</a> covers other kinds of brushes.
			The <span class="code">SolidBrush</span> class implements the functionality of a solid-colour brush. See the example below:
		</p>
		
		<div class="sampleCode">Graphics g = new Graphics("Square.pdf");

SolidBrush myBrush = new SolidBrush(Rgb.Green);

g.FillRectangle(myBrush, 20, 20, 100, 100);

g.Close();</div>
		
		<p>This fills a square with a solid green colour. Note that we could have written line 2 as follows:</p>
		
		<div class="sampleCode">Brush myBrush = new SolidBrush(Rgb.Green);</div>
			
		<p>
			The <span class="code">SolidBrush</span> class inherits from <span class="code">Brush</span>,
			the base class for all brushes.
		</p>
		
		<p>For a shape that is outlined as well as filled in, perform the two operations consecutively:</p>

		<div class="sampleCode">Graphics g = new Graphics("Square.pdf");

Pen myPen = new Pen(Rgb.Red);
SolidBrush myBrush = new SolidBrush(Rgb.Green);

g.DrawRectangle(myPen, 20, 20, 100, 100);
g.FillRectangle(myBrush, 20, 20, 100, 100);

g.Close();</div>
	
		<h2><a name="Colours"></a>Colours</h2>
		
		<p>
			In the examples above, we created coloured brushes and pens using a short-hand notation; for a number of common colours,
			PDF Graphics .NET offers pre-created brushes and pens. To create our own brushes and pens, we need to create
			the colours manually. See the example below (lines omitted for brevity):
		</p>

		<div class="sampleCode">Colour orange = new RgbColour(255, 180, 50);
Brush orangeBrush = new SolidBrush(orange);
			
g.FillRectangle(orangeBrush, 20, 20, 100, 100);</div>
	
		<p>
			The example code creates a new <span class="code">RgbColour</span> instance and uses it to create a brush to fill the rectangle with.
			The <span class="code">RgbColour</span> class represent a RGB colour, defined by red, green and blue components. We will be using
			RGB colours for the moment, because they are familiar. The <a href="Colour_schemes.html">Colour schemes</a> section will
			provide full coverage of the colour schemes supported by PDF Graphics .NET.
		</p>
		
		<h2><a name="Lines"></a>Drawing lines</h2>
		
		<p>
			In the above sections we used the <span class="code">Pen</span> class to draw lines. So far, we've only used solid lines.
			The <span class="code">Pen</span> class can be used to draw dotted or dashed lines, too. See the example code below:
		</p>
		
		<div class="sampleCode">Pen dashedPen = new Pen(Rgb.Black, new int[] { 4, 2 });
g.DrawRectangle(dashedPen, 20, 20, 50, 50);</div>

		<p>This produces the following output:</p>

		<img src="../images/PatternPen.jpg"/>
		
		<p>
			The numbers (4,2) specify the length, in points, of the dashes and the spaces in between (no matter the thickness of the pen stroke).
			The pattern is not limited to two numbers; more elaborate ones are possible, such as the following dash-dot one:
		</p>

		<div class="sampleCode">Pen dashDot = new Pen(Rgb.Black, new int[] { 4, 2, 2, 2 });</div>
		
		<p>
			It is possible to specify a list of numbers of uneven length, too; the pen's alternating strokes and spaces are
			determined by cycling through the numbers so a list of uneven length will simply result in a less predictable pattern.
		</p>
		
		<h2><a name="LineAppearance"></a>Line appearance</h2>
		
		<p>
			The <span class="code">Pen</span> class has two more properties that determine the appearance of lines; <span class="code">LineCapStyle</span>
			and <span class="code">LineJoinStyle</span>. These allow fine-tuning of the appearance of lines at their end points or when two lines
			meet at an angle.
		<p>
			
		<h3>Line cap</h3>
		
		<p>The <span class="code">LineCapStyle</span> property controls the appearance of end points of a line:</p>
		
		<table width="800">
			<thead>
				<th colspan="3">Line cap styles</td>
			</thead>
			<tr>
				<th class="left">Value of <span class="code">LineCapStyle</span></td>
				<th width="200">Example</td>
				<th class="left">Description</td>
			</tr>
			<tr>
				<td><span class="code">LineCapStyle.Butt</span></td>
				<td class="centered"><img src="../images/LineCapStyleButt.jpg"/></td>
				<td>A line with butt endings has no projection; the line ends exactly at its end points, and the endings are square. This is the default value.</td>
			</tr>
			<tr>
				<td><span class="code">LineCapStyle.Rounded</span></td>
				<td class="centered"><img src="../images/LineCapStyleRounded.jpg"/></td>
				<td>A line with rounded endings extends beyond its endpoints by half its width, and the endings are demi-circles.</td>
			</tr>
			<tr>
				<td><span class="code">LineCapStyle.ProjectingSquare</span></td>
				<td class="centered"><img src="../images/LineCapStyleProjectingSquare.jpg"/></td>
				<td>A line with projecting square endings extends beyond its endpoints by half its width, and the endings are square.</td>
			</tr>
		</table>
			
		<h3>Line join</h3>
		
		<p>The <span class="code">LineJoinStyle</span> property controls the appearance of lines when they meet an angle:</p>
		
		<table width="800">
			<thead>
				<th colspan="3">Line join styles</td>
			</thead>
			<tr>
				<th class="left">Value&nbsp;of&nbsp;<span class="code">LineJoinStyle</span></td>
				<th width="200">Example</td>
				<th class="left">Description</td>
			</tr>
			<tr>
				<td><span class="code">LineJoinStyle.Miter</span></td>
				<td class="centered"><img src="../images/LineJoinStyleMiter.jpg"/></td>
				<td>When lines are joined using the Miter style, their outer edges join at an angle, creating a sharp pointed ending. This is the default value.</td>
			</tr>
			<tr>
				<td><span class="code">LineJoinStyle.Round</span></td>
				<td class="centered"><img src="../images/LineJoinStyleRound.jpg"/></td>
				<td>When lines are joined using the Round style, the outer edges join through an arc, giving the join a rounded look.</td>
			</tr>
			<tr>
				<td><span class="code">LineJoinStyle.Bevel</span></td>
				<td class="centered"><img src="../images/LineJoinStyleBevel.jpg"/></td>
				<td>When lines are joined using the Bevel style, their outer edges are joined by a straight piece similar to the squared end of a Butt cap.</td>
			</tr>
		</table>
							
		<h3><strong>Navigation options:</strong></h3>
		<p><a href="..\Painting_graphics.html">&lt; Painting graphics</a> | <a href="Shapes.html">Shapes &gt;</a>
				
	</body>
	
</html>